home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / chariter.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  7KB  |  198 lines
  1.  
  2. /*
  3. ********************************************************************
  4. * COPYRIGHT: 
  5. * (C) Copyright Taligent, Inc., 1997
  6. * (C) Copyright International Business Machines Corporation, 1997 - 1998
  7. * Licensed Material - Program-Property of IBM - All Rights Reserved. 
  8. * US Government Users Restricted Rights - Use, duplication, or disclosure 
  9. * restricted by GSA ADP Schedule Contract with IBM Corp. 
  10. *
  11. ********************************************************************
  12. */
  13.  
  14. #ifndef CHARITER_H
  15. #define CHARITER_H
  16.  
  17. #include "utypes.h"
  18. #include "unistr.h"
  19.  
  20.  
  21. /**
  22.  *  Abstract class defining a protcol for accessing characters in a text-storage object.
  23.     <P>Examples:<P>
  24.  
  25.     Function processing characters, in this example simple output
  26.     <pre>
  27.     .   void processChar( UChar c )
  28.     .   {
  29.     .       cout << " " << c;
  30.     .   }
  31.     </pre>
  32.     Traverse the text from start to finish
  33.     <pre> 
  34.     .   void traverseForward(CharacterIterator& iter)
  35.     .   {
  36.     .       for(UChar c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
  37.     .           processChar(c);
  38.     .       }
  39.     .   }
  40.     </pre>
  41.     Traverse the text backwards, from end to start
  42.     <pre>
  43.     .   void traverseBackward(CharacterIterator& iter)
  44.     .   {
  45.     .       for(UChar c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) {
  46.     .           processChar(c);
  47.     .       }
  48.     .   }
  49.     </pre>
  50.     Traverse both forward and backward from a given position in the text. 
  51.     Calls to notBoundary() in this example represents some additional stopping criteria.
  52.     <pre>
  53.     .   void traverseOut(CharacterIterator& iter, UTextOffset pos)
  54.     .   {
  55.     .       UChar c;
  56.     .       for (c = iter.setIndex(pos);
  57.     .       c != CharacterIterator.DONE && (Unicode::isLetter(c) || Unicode::isDigit(c));
  58.     .           c = iter.next()) {}
  59.     .       UTextOffset end = iter.getIndex();
  60.     .       for (c = iter.setIndex(pos);
  61.     .           c != CharacterIterator.DONE && (Unicode::isLetter(c) || Unicode::isDigit(c));
  62.     .           c = iter.previous()) {}
  63.     .       UTextOffset start = iter.getIndex() + 1;
  64.     .   
  65.     .       cout << "start: " << start << " end: " << end << endl;
  66.     .       for (c = iter.setIndex(start); iter.getIndex() < end; c = iter.next() ) {
  67.     .           processChar(c);
  68.     .       }
  69.     .    }
  70.     </pre>
  71.     Creating a StringCharacterIteratorand calling the test functions
  72.     <pre>
  73.     .    void CharacterIterator_Example( void )
  74.     .    {
  75.     .        cout << endl << "===== CharacterIterator_Example: =====" << endl;
  76.     .        UnicodeString text("Ein kleiner Satz.");
  77.     .        StringCharacterIterator iterator(text);
  78.     .        cout << "----- traverseForward: -----------" << endl;
  79.     .        traverseForward( iterator );
  80.     .        cout << endl << endl << "----- traverseBackward: ----------" << endl;
  81.     .        traverseBackward( iterator );
  82.     .        cout << endl << endl << "----- traverseOut: ---------------" << endl;
  83.     .        traverseOut( iterator, 7 );
  84.     .        cout << endl << endl << "-----" << endl;
  85.     .    }
  86.     </pre>
  87.  */
  88. class U_COMMON_API CharacterIterator
  89. {
  90. public:
  91.   /**
  92.    * Value returned by most of CharacterIterator's functions
  93.    * when the iterator has reached the limits of its iteration.  */
  94.   static const UChar    DONE;
  95.  
  96.   /**
  97.    * Destructor.  */
  98.   virtual ~CharacterIterator();
  99.  
  100.   /**
  101.    * Returns true when both iterators refer to the same
  102.    * character in the same character-storage object.  */
  103.   virtual bool_t          operator==(const CharacterIterator& that) const = 0;
  104.         
  105.   /**
  106.    * Returns true when the iterators refer to different
  107.    * text-storage objects, or to different characters in the
  108.    * same text-storage object.  */
  109.   bool_t                  operator!=(const CharacterIterator& that) const { return !operator==(that); }
  110.  
  111.   /**
  112.    * Returns a pointer to a new CharacterIterator of the same
  113.    * concrete class as this one, and referring to the same
  114.    * character in the same text-storage object as this one.  The
  115.    * caller is responsible for deleting the new clone.  */
  116.   virtual CharacterIterator*
  117.   clone(void) const = 0;
  118.  
  119.   /**
  120.    * Generates a hash code for this iterator.  */
  121.   virtual int32_t         hashCode(void) const = 0;
  122.         
  123.   /**
  124.    * Sets the iterator to refer to the first character in its
  125.    * iteration range, and returns that character, */
  126.   virtual UChar         first(void) = 0;
  127.         
  128.   /**
  129.    * Sets the iterator to refer to the last character in its
  130.    * iteration range, and returns that character.  */
  131.   virtual UChar         last(void) = 0;
  132.         
  133.   /**
  134.    * Sets the iterator to refer to the "position"-th character
  135.    * in the text-storage object the iterator refers to, and
  136.    * returns that character.  */
  137.   virtual UChar         setIndex(UTextOffset position) = 0;
  138.  
  139.   /**
  140.    * Returns the character the iterator currently refers to.  */
  141.   virtual UChar         current(void) const = 0;
  142.         
  143.   /**
  144.    * Advances to the next character in the iteration range
  145.    * (toward last()), and returns that character.  If there are
  146.    * no more characters to return, returns DONE.  */
  147.   virtual UChar         next(void) = 0;
  148.         
  149.   /**
  150.    * Advances to the previous character in the iteration rance
  151.    * (toward first()), and returns that character.  If there are
  152.    * no more characters to return, returns DONE.  */
  153.   virtual UChar         previous(void) = 0;
  154.  
  155.   /**
  156.    * Returns the numeric index in the underlying text-storage
  157.    * object of the character returned by first().  Since it's
  158.    * possible to create an iterator that iterates across only
  159.    * part of a text-storage object, this number isn't
  160.    * necessarily 0.  */
  161.   virtual UTextOffset      startIndex(void) const = 0;
  162.         
  163.   /**
  164.    * Returns the numeric index in the underlying text-storage
  165.    * object of the position immediately BEYOND the character
  166.    * returned by last().  */
  167.   virtual UTextOffset      endIndex(void) const = 0;
  168.         
  169.   /**
  170.    * Returns the numeric index in the underlying text-storage
  171.    * object of the character the iterator currently refers to
  172.    * (i.e., the character returned by current()).  */
  173.   virtual UTextOffset      getIndex(void) const = 0;
  174.  
  175.   /**
  176.    * Copies the text under iteration into the UnicodeString
  177.    * referred to by "result".  @param result Receives a copy of
  178.    * the text under iteration.  */
  179.   virtual void            getText(UnicodeString&  result) = 0;
  180.  
  181.   /**
  182.    * Returns a UClassID for this CharacterIterator ("poor man's
  183.    * RTTI").<P> Despite the fact that this function is public,
  184.    * DO NOT CONSIDER IT PART OF CHARACTERITERATOR'S API!  */
  185.   virtual UClassID         getDynamicClassID(void) const = 0;
  186.  
  187. protected:
  188.   CharacterIterator() {}
  189.   CharacterIterator(const CharacterIterator&) {}
  190.   CharacterIterator&      operator=(const CharacterIterator&) { return *this; }
  191.     
  192. };
  193.  
  194. #endif
  195.  
  196.  
  197.  
  198.